|
(SST) ShlWAPI.pas Version 1.08 |
|---|---|
| Developer Reference |
| Parses a path and returns a pointer to the first component below the path's root. |
| Scope |
|---|
| Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas). |
| Syntax | |
|---|---|
 |
function PathSkipRoot(pszPath : LPCSTR) : LPSTR; |
| Parameters | |
|---|---|
| pszPath [in] | Depending on which version of the function is called, a pointer to the zero terminated, ANSI or Unicode string that is the path to parse. It should not exceed MAX_PATH (= 260 characters, including the terminating null character) in length. |
| Return Values |
|---|
| If the input string is a fully qualified, DOS/Windos path, the function returns a pointer to the the beginning of the first component below the root. If the input string is an absolute path that does not contain a component below the root, the function returns a pointer to the input string's terminating NULL character. If the path passed to the function is not an absolute/fully qualified path or the function fails for any other reason, it returns NIL. |
| Remarks |
|---|
| The function does not modify the contents of the memory range containg the input string in any form or manner. |
| If the function returns a pointer that is not NIL, it either points to an address within the string/buffer containing the original path or its terminating null-character. |
| Unlike some other Windows API functions that process path strings, PathSkipRoot fails if called with a path in which slashes ("/") instead of backslashes ("\") separate one or more path components. |
| The function can process both regular, Windows as well ss Universal Naming Convention (UNC) paths. If a UNC path is passed to the function the absence of a share name will not cause it to fail. In this case, it will return a pointer to the terminating null-character. |
| Unlike some other Windows API functions that process path strings, PathSkipRoot appears to perform a syntax check. |
| Example |
|---|
| PROCEDURE TForm4.TestShlWAPIPathSkipRoot(Sender : TObject); VAR pathtotest : STRING; VAR apiretptr : PChar; VAR newinfoline : STRING; BEGIN pathtotest := ''; apiretptr := NIL; newinfoline := ''; pathtotest := 'C:\Windows\System32\Kernel32.dll'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); pathtotest := 'X:\'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); pathtotest := '\\SAMPLESRVER\Share\RemoteFolder\RemoteFile.ext'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); pathtotest := 'C:\PROGRA~1\SST\NewApp'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); pathtotest := 'InvalidRootFolder\SubFolder\FileNoExt'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); pathtotest := '..\RelativeFolder1\FileName1.ext'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); pathtotest := '.\RelativeFolder2\FileName2.ext'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); pathtotest := '\\SAMPLESRVER\SharedFolder\'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); pathtotest := 'http://sampledomain.smp/samplefolder/page.htm'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); pathtotest := 'Z:/UnixFolder/SubDir/UnixFile.ext'; newinfoline := 'PathSkipRoot called with ' + pathtotest; Memo1.Lines.Add(newinfoline); apiretptr := PathSkipRoot(PChar(pathtotest)); IF apiretptr <> NIL THEN BEGIN IF apiretptr <> StrEnd(PChar(pathtotest)) THEN newinfoline := 'Result: ' + apiretptr ELSE newinfoline := 'Result: NULL character that terminates the input string'; END ELSE newinfoline := 'PathSkipRoot returned NIL !'; Memo1.Lines.Add(newinfoline); Memo1.Lines.Add(''); END; |
| Under Windows Vista with Service Pack 1 (SP 1) and IE 8 the above code producesd the following output: |
| PathSkipRoot called with C:\Windows\System32\Kernel32.dll Result: Windows\System32\Kernel32.dll PathSkipRoot called with X:\ Result: NULL character that terminates the input string PathSkipRoot called with \\SAMPLESRVER\Share\RemoteFolder\RemoteFile.ext Result: RemoteFolder\RemoteFile.ext PathSkipRoot called with C:\PROGRA~1\SST\NewApp Result: PROGRA~1\SST\NewApp PathSkipRoot called with InvalidRootFolder\SubFolder\FileNoExt PathSkipRoot returned NIL ! PathSkipRoot called with ..\RelativeFolder1\FileName1.ext PathSkipRoot returned NIL ! PathSkipRoot called with .\RelativeFolder2\FileName2.ext PathSkipRoot returned NIL ! PathSkipRoot called with \\SAMPLESRVER\SharedFolder\ Result: NULL character that terminates the input string PathSkipRoot called with http://sampledomain.smp/samplefolder/page.htm PathSkipRoot returned NIL ! PathSkipRoot called with Z:/UnixFolder/SubDir/UnixFile.ext PathSkipRoot returned NIL ! |
| Requirements | |
|---|---|
| Unit: | Declared and imported in (SST)ShlWAPI.pas |
| Library: | (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj |
| Unicode: | Implemented as ANSI (PathSkipRoot and PathSkipRootA) and Unicode (PathSkipRootW) functions. |
| Min. ShlWAPI.dll version according to MS SDK doc.: | 4.71 |
| Min. ShlWAPI.dll version based on SST research: | 4.71 |
| Min. OS version(s) according to Microsoft SDK doc.: | Windows 2000, Windows NT 4.0 with Internet Explorer 4.0, Windows 98, Windows 95 with Internet Explorer 4.0 |
| Min. OS version(s) according to SST research.: | Windows NT 4.0 with IE 4.0, Windows 95 with IE 4.0, Windows 98 and later |
| See Also |
|---|
| PathIsPrefix, PathIsRelative, PathIsRoot. |
| Windows APIs: GetLastError, SetLastError PathSkipRoot, PathIsPrefix, PathIsRelative, PathIsRoot, PathBuildRoot PathStripToRoot |
|
Document/Contents version 1.00 Page/URI last updated on 07.12.2023 |
Copyright © Stoelzel Software Technologie (SST) 2010 - 2015 |
Suggestions and comments mail to: webmaster@stoelzelsoftwaretech.com |